home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 11 / Mac Magazin and MacEasy Magazine CD - Issue 11.iso / Sharewarebibliothek / Entwickler / appe Windows 2.0 / About appe Windows next >
Text File  |  1995-06-11  |  12KB  |  251 lines
  1. appe Windows 2.0
  2. ================
  3. If you have seen the new Speech Manager, then you know that a background
  4. only application can put a window onto the screen (contrary to popular
  5. belief). The new Text Services Manager in System 7.1 offers documented
  6. hooks for creating, disposing, and handling floating windows. These
  7. windows are layer independent (they are floating above all programs and
  8. windows), and can work without patching traps (well, a quick jGNEFilter,
  9. but no traps).
  10.  
  11. This program demonstrates a shell application that puts a TSM window onto
  12. the screen, and intercepts update, click, and key events. You can use
  13. "sample win.c" and "sample drag.c" to see how to write your own handlers,
  14. and easily add your desired functionality within a few hours. If you don't
  15. care to look behind the scenes, you simply write the handlers from the 
  16. templates. If you want to see how it really works, you can lift the curtains
  17. and look in the other functions for yourself.
  18.  
  19. The program can work as a foreground or background-only application. The
  20. software is distributed as a foreground app, but the process to convert a
  21. program to background app is to set the "Background Only" flag in the
  22. 'SIZE' resource (or Project Flags) and to make a system extension, you
  23. should change the file type from 'APPL' to 'appe'. I have added a
  24. drag-n-drop utility to convert between foreground and background apps, as
  25. well as a file describing the differences.
  26.  
  27. I like the close box on floater windows, because its an easy way to quit
  28. the program without relying on a quit Apple Event. I have added support
  29. for hiding windows with Cmd-Escape, and to respond to screen savers and
  30. programs that take over the screen (hide the menu bar).
  31.  
  32.  
  33. What's New in 2.0?
  34. ==================
  35. Um, the whole thing. I rewrote the entire program with CodeWarrior 6 to
  36. get it to generate both 68k and PPC code -- and trust me, its *sooooo* 
  37. much cleaner code in these ways:
  38.  
  39.     * Totally reorganized the file structure into 4 groups: Main Stuff
  40.       (main.c, aevents.c, prefs.c), Filters/Patches(filter.c, patches.c),
  41.       Floater Mgmt Utils (floaters.c), and Sample Handlers(sample win.c,
  42.       sample drag.c).
  43.     * 68k jGNEFilter will call a Native helper function. (I am still 
  44.       working on a native jGNEFilter, so any hints are appreciated!)
  45.     * Greatly improved Install and Remove jGNEFilter utility routines.
  46.       It will now try to remove the 50 byte filter from the System heap.
  47.     * All filtered events are now forwarded to the application to 
  48.       be handled in our context -- eliminating context-switching 
  49.       resource files, heap zones, and GrafPtrs. 
  50.     * Gracefully handle multiple windows, and even supports different
  51.       kinds of windows easily. Also, it includes and uses internal 
  52.       routines to navigate and select internal own floater windows.
  53.     * Clarified and collected window handling routines... its almost
  54.       suitable for converting to C++.
  55.     * The sample window code is pretty robust and extendable. In fact
  56.       I even added some Drag Manager support for the sample window.
  57.     * Added (optional) ExitToShell cleanup patch, to ease debugging.
  58.     * I am certain my hiding and showing code works right now, and is
  59.       flexible enough for most applications.
  60.     * A new version of "TSM Fix" is enclosed which should fix any 
  61.       incompatibilities with certain extensions and debuggers.
  62.  
  63.  
  64. Fixes/Changes since the 2.0 beta
  65.     * Fixed a problem that EBBE flags -- the floater accessor functions
  66.       used to blindly dereference qTail without first testing it. 
  67.     * Added an attempt to remove the jGNEFilter from the System Heap 
  68.       if it is the first one in the chain.
  69.     * Force faster updates when creating a sample window or after changing
  70.       its contents.
  71.     * Added Drag Mgr support for receiving Text Files (as well as simple
  72.       text clippings).
  73.     * Completely rewrote the notification mechanism to clean up after itself
  74.       a little better, provide optional ExitToShell() service, and to
  75.       prevent the floaters from obscuring the Notification dialog.
  76.     * Added a message that informs the user to install "TSM Fix" if it
  77.       hasn't been installed by run time. 
  78.     * Added a SC (7.04) project with the source files stripped of Univ. 
  79.       Headers, UPP's, and LowMem accessors (I also changed the WDEF from
  80.       FAT to 68K). However I didn't change the comments within the source
  81.       files to reflect this, so just read them carefully. Note: You may
  82.       need to add the indicated header files to your compiler's
  83.       "Apple #includes" subdirectory.
  84.  
  85. Legal Stuff
  86. ===========
  87. Its yours if you like it. This shell is free for you to modify and
  88. expand upon. I would like it if you tell me if you use this, but you
  89. are under no obligation. Likewise, this library is provided as is --
  90. I fixed up all the bugs I could find/create, so I could use it myself --
  91. but that doesnt necessarily mean its fit for wiping the toilet seat. :)
  92.  
  93. The enclosed extension "TSM Fix" is intended to fix problems with the
  94. jGNEFilter missing clicks bug. This INIT is also free, to be distributed
  95. with (or without) any software you have written.
  96.  
  97. In addition, the enclosed utility "appe <-> APPL" is useful so that you
  98. only have to distribute a single binary form. Again, the program is free 
  99. to be redistributed at your whim.
  100.  
  101. The cool floating window WDEF used is the Infinity Windoid by Troy Gaul.
  102. The WDEF is free, but you should read the accompanying documentation and
  103. download the full Infinity Windoid package -- it really rox!  PS - You 
  104. may consider distributing the appropriate WDEF (68K, PPC, Fat) with each
  105. version of your program. All versions (68K, PPC, Fat) of the sample project
  106. compile with just the Fat WDEF.
  107.  
  108.  
  109. Using the library
  110. =================
  111. In scanning the source for the program, there are several key areas
  112. that you should recognize. These gotchas are important things to 
  113. remember when modifying or adding to the source.
  114.  
  115. main.c
  116.     
  117.     Faceless background applications seem to require additional stack
  118.     space. I found that 16k of additional stack seems to work. BTW, 
  119.     you want keep the memory footprint down (people dont like memory
  120.     hogs) but not too small or you will have heap space problems. I
  121.     had to fine tune my demo apps to work well in limited memory space.
  122.     
  123.     In a background-only application, the only Toolbox initialization
  124.     call that you should make is InitGraf() to setup the QD globals.
  125.     InitWindows() plays with the layer manager in a bad way, and
  126.     should be avoided.
  127.     
  128.     Use Gestalt() to check the runtime environment, and exit gracefully
  129.     with a Notification Mgr dialog.
  130.     
  131.     The event loop sucks incoming events from both WaitNextEvent() and
  132.     from a queue of forwarded events from the Event Filter. These are
  133.     dispatched automatically, as well as resolving any pending update
  134.     events.
  135.  
  136. notify.c
  137.     
  138.     A simple installer and cleanup code for posting notifications safely,
  139.     even if we are about to quit. Also set/clear a flag to keep floaters
  140.     from obscuring important notices (since Notification Mgr. interferes
  141.     with our forwarded event mechanism). BTW, if you can come up with a 
  142.     better way to dispose the memory allocated using inline code (no 
  143.     resources, etc), I would like to hear.
  144.  
  145. filter.c
  146.  
  147.     The jGNEFilter is the best way to intercept the events directed 
  148.     at our window. We check mouse and key events for relevance, and
  149.     then forward them them to the application's event loop. In this
  150.     version, the only context you get is a valid globals world --
  151.     you CAN'T handle user or update events here. They must be done
  152.     from our (complete and full) context.
  153.     
  154.     Note: the jGNEFilter may miss occasional mouse-downs. Its a bug
  155.     in the OS, and you need to look at my "TSM Fix" for a patch that
  156.     rememdies the problem. 
  157.     
  158.     Our floaters dont get update events either, so we manually
  159.     check the update region of our window and call the update
  160.     routine. We have to check every event because update events
  161.     aren't necessarily posted when just our window needs
  162.     drawing.
  163.     
  164.     Key events can be intercepted or passed through at your discretion.
  165.     By default, only Cmd-Escape is applicable and it toggles the 
  166.     visibility of the floaters. (This would be a useful feature for all
  167.     similar apps to implement, please?)
  168.     
  169.     (v2.0) Updated the TestScreenSaver() function to be so much smarter
  170.     and work from within the jGNEFilter and our own context.
  171.     
  172. patches.c
  173.     
  174.     The current TSM does not create a Color Window for us, so by default
  175.     we patch NewWindow to enable the desired functionality. Although this
  176.     violates our promise of patch-free operation, it gives us color --
  177.     so lose or leave it at your whim.
  178.     
  179.     (v2.0) Add a patch to ExitToShell() that cleans up if any unexpected
  180.     errors occur (esp. while debugging). Again, its up to you if you want
  181.     this in your final product -- but I consider it essential.
  182.  
  183. floaters.c
  184.     
  185.     The floater functionality parallels NewWindow(), CloseWindow(), and 
  186.     DisposeWindow() routines. When creating a floater, you should also
  187.     specify callbacks to handle events or close requests. In addition, you
  188.     can pick a "Hot Application" in which the floater will be visible (and 
  189.     hidden at all other times) or pass zero to remain visible at all times.
  190.     This is a great way to give specialized information about a particular 
  191.     program without modifying it.
  192.     
  193.     Utility routines let you walk the internal window list and extract
  194.     additional information, either by window lookup or by index. These are
  195.     used internally for updating or hiding/showing floaters, but the sample
  196.     window routines are free to use them.
  197.     
  198.     ShowHide and Update routines let you select a particular window, or
  199.     (by passing a NIL WindowPtr) walk the list of all our floaters.
  200.     
  201.     Handling events or closing all windows are sent to dispatch routines
  202.     that can find the proper handlers and forward the little events along.
  203.     
  204. sample win.c
  205.  
  206.     When creating the window, we manage a set of prefs that keep track 
  207.     how many windows we have creating. This lets us offset each new 
  208.     window, and give it an incremental title across launches. 
  209.     
  210.     The sample window code implements the necessary callbacks that 
  211.     receive incoming window events and close imperatives. That code is
  212.     responsible then for handling clicks, hotkeys, and updates.
  213.  
  214.     Controls like scroll bars or other window-activation sensitive 
  215.     elements should always be active in floaters, since all floaters
  216.     are considered active regardless of position in window list.
  217.  
  218.     The content text for the sample windows are stored off the RefCon, but
  219.     you should do anything you like for the refcon or drawing routines.
  220.     
  221. sample drag.c
  222.     
  223.     Hey, its just a demo. You can try it out, expand on it, or just rip
  224.     it out depending on what kind of utility you are writing. It supports
  225.     sending text data and receiving both text data and text files.
  226.  
  227. Compiling Fat Apps
  228.     
  229.     Since you see 2 projects, one for 68K and one for PPC, you may not 
  230.     see how to combine the files to make Fat application.  The trick I
  231.     used was to compile both 68K and PPC versions -- which should be 
  232.     identical except where the real code is located (68K='CODE' resources, 
  233.     PPC=Data Fork & 'cfrg' rsrc.) Duplicate the PPC binary, then use
  234.     ResEdit to copy over the 'CODE' resources from the 68K binary to 
  235.     the new Fat version. Voila, both 68K and PPC can run the right code.
  236.  
  237.     Again, I used the Fat Infinity Windoid for all 3 binaries. You may
  238.     decide to replace the copies in your 68K and PPC versions with the
  239.     CPU-specific version -- but be careful when compiling a Fat version
  240.     to use the Fat (or 68K) WDEF.
  241.  
  242.  
  243. Finally, I want this to be a stable mechanism for something that you
  244. shouldn't be able to do. Despite the interface guidelines, there may
  245. be a use for doing this. Please send me bug reports and suggestions
  246. for improving this tool.
  247.  
  248. Matt Slot
  249. fprefect@umich.edu
  250. 
  251.